Skip to content

docs: clarify commands and skills use same Skill tool mechanism #201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
sjnims merged 2 commits into from
Jan 28, 2026
Merged

docs: clarify commands and skills use same Skill tool mechanism #201

sjnims merged 2 commits into from
Jan 28, 2026

Conversation

@sjnims
Copy link
Owner

@sjnims sjnims commented Jan 28, 2026

Description

Update documentation to reflect Anthropic's conceptual merge of slash commands and skills. Both are now invoked via the same Skill tool but differ in complexity level:

  • Commands (commands/): Simple .md files for quick prompts
  • Skills (skills/name/): Full directories with bundled resources (scripts, references, examples)

Thanks to @KRRT7 for opening the issue!

Type of Change

  • Documentation update (improvements to README, CLAUDE.md, or component docs)

Component(s) Affected

  • Skills (methodology and best practices)
  • Documentation (README.md, CLAUDE.md, SECURITY.md)

Motivation and Context

Anthropic has merged the concepts of slash commands and skills at the mechanism level—both are now invoked via the Skill tool. This PR updates plugin-dev documentation to clearly explain this relationship while maintaining the organizational distinction (commands = simple, skills = complex with resources).

Fixes #198

How Has This Been Tested?

Test Configuration:

  • Claude Code version: Latest
  • GitHub CLI version: 2.67.0
  • OS: macOS Darwin 25.2.0

Test Steps:

  1. Ran markdownlint 'plugins/plugin-dev/**/*.md' --ignore node_modules - passes
  2. Ran npx prettier --write on modified files
  3. Verified all modified files render correctly

Checklist

General

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • My changes generate no new warnings or errors

Documentation

  • I have updated the documentation accordingly (README.md, CLAUDE.md, or component docs)
  • I have verified all links work correctly

Markdown

  • I have run markdownlint and fixed all issues
  • My markdown follows the repository style (ATX headers, dash lists, fenced code blocks)

Version Management (if applicable)

  • I have updated CHANGELOG.md with relevant changes

Files Changed

File Change
skills/command-development/SKILL.md Added "Commands and Skills: Same Mechanism, Different Complexity" section
skills/skill-development/SKILL.md Added "Skills and Commands: Unified Mechanism" section
skills/plugin-structure/SKILL.md Updated Commands and Skills component descriptions
skills/plugin-dev-guide/SKILL.md Updated quick reference table and decision tree
skills/command-development/references/skill-tool.md Added key insight note
skills/skill-development/references/commands-vs-skills.md NEW - Decision matrix and migration guide
CHANGELOG.md Added entries under [Unreleased]

Additional Notes

The approach keeps commands and skills as separate concepts from an organizational standpoint while making clear they share the same invocation mechanism. This aligns with how plugin developers should think about the choice: complexity needs drive whether to use a simple command or a full skill with resources.

🤖 Generated with Claude Code

@sjnims @claude
docs: clarify commands and skills use same Skill tool mechanism
aae2ff9 
Update documentation to reflect Anthropic's conceptual merge of slash
commands and skills. Both are now invoked via the Skill tool but differ
in complexity level:

- Commands: Simple .md files in commands/ for quick prompts
- Skills: Full directories in skills/ with bundled resources

Changes:
- Add "Commands and Skills: Same Mechanism" section to command-development
- Add "Skills and Commands: Unified Mechanism" section to skill-development
- Update plugin-structure component descriptions
- Update plugin-dev-guide quick reference and decision tree
- Add key insight note to skill-tool.md reference
- Create new commands-vs-skills.md reference with decision matrix

Fixes #198

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@sjnims sjnims self-assigned this Jan 28, 2026
@claude
Copy link

claude bot commented Jan 28, 2026 •
edited
Loading

Claude finished @sjnims's task in 55s —— View job

PR Review: docs: clarify commands and skills use same Skill tool mechanism

Tasks

  • Run quality checks (markdownlint, prettier)
  • Review the diff for all changed files
  • Check plugin component standards
  • Provide feedback with verdict

Verdict: ✅ Looks good

This is a well-structured documentation update that clearly explains the conceptual merge of commands and skills while maintaining the practical organizational distinction.

Quality Checks

Check Result
markdownlint ✅ Pass (0 errors)
prettier ✅ Pass (all files formatted)
shellcheck N/A (no shell scripts changed)

What's Good

  1. Consistent messaging across files - The "same mechanism, different complexity" concept is reinforced in multiple locations without being redundant

  2. Practical decision guidance - The new commands-vs-skills.md reference provides a clear decision matrix and migration path

  3. Updated quick reference table - The plugin-dev-guide changes align the skill descriptions with the new conceptual model

  4. Progressive disclosure pattern - Information is layered appropriately:

    • Quick mentions in SKILL.md files
    • Detailed reference in commands-vs-skills.md
    • Key insight note in skill-tool.md

  5. Invocation control table - Clear documentation of the three invocation settings (default, disable-model-invocation, user-invocable)

Suggestions

  1. Consider adding a cross-reference - In skills/command-development/SKILL.md:76 where the new section ends with "convert the command to a skill", you might link to skill-development skill for the detailed process

  2. Minor: Migration section in commands-vs-skills.md - The migration steps are good but step 2 mentions "Move command content to SKILL.md body" - consider noting that the frontmatter fields (description, allowed-tools, etc.) are preserved since they work identically

These are minor polish suggestions, not blockers.

Files Reviewed

File Status
CHANGELOG.md ✅ Proper changelog format
skills/command-development/SKILL.md ✅ Good comparison table
skills/command-development/references/skill-tool.md ✅ Key insight note well-placed
skills/plugin-dev-guide/SKILL.md ✅ Updated descriptions accurate
skills/plugin-structure/SKILL.md ✅ Brief clarifications appropriate
skills/skill-development/SKILL.md ✅ Unified mechanism explained
skills/skill-development/references/commands-vs-skills.md ✅ Comprehensive new reference

@claude claude bot added documentation Improvements or additions to documentation effort:small < 1 hour component:skill Skills layer component:docs Documentation files labels Jan 28, 2026
@sjnims @claude
docs: address review suggestions
547715b 
- Add cross-reference to skill-development skill in command-development
- Note that frontmatter fields are preserved during command-to-skill migration

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@sjnims
Copy link
Owner Author

sjnims commented Jan 28, 2026

Addressed review suggestions in 547715b:

  • Added cross-reference to skill-development skill
  • Noted frontmatter field preservation in migration steps

@claude
Copy link

claude bot commented Jan 28, 2026 •
edited
Loading

Claude finished @sjnims's task in 1m 22s —— View job

PR Review: docs: clarify commands and skills use same Skill tool mechanism

Tasks

  • Run quality checks (markdownlint, prettier)
  • Review the diff for all changed files
  • Check for issues addressed in latest commit
  • Provide feedback with verdict

Verdict: ✅ Looks good

Both suggestions from the previous review have been addressed in commit 547715b:

  1. ✅ Cross-reference added - command-development/SKILL.md:74 now links to the skill-development skill for migration guidance
  2. ✅ Frontmatter preservation noted - commands-vs-skills.md:36 clarifies that frontmatter fields work identically when migrating

Quality Checks

Check Result
markdownlint ⚠️ Unable to run (tools not available)
prettier ⚠️ Unable to run (tools not available)
shellcheck N/A (no shell scripts changed)

Note: The linting tools were not pre-installed. The PR description indicates the author ran these checks locally and they passed.

What's Good

  1. Suggestions implemented cleanly - Both additions integrate naturally into the existing documentation flow

  2. Cross-reference placement is ideal - The link to skill-development appears right after the "when to graduate" guidance at line 74, exactly where a reader would want it

  3. Migration guidance is actionable - The parenthetical note about frontmatter fields working identically provides helpful reassurance to developers migrating commands to skills

Files Reviewed

File Status Notes
command-development/SKILL.md ✅ Updated Added cross-reference to skill-development
commands-vs-skills.md ✅ Updated Added frontmatter preservation note

This PR is ready to merge.

@sjnims sjnims merged commit 4ac34c2 into main Jan 28, 2026
8 checks passed
@sjnims sjnims deleted the docs/commands-skills-merge-198 branch January 28, 2026 01:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@sjnims sjnims

Labels

component:docs Documentation files component:skill Skills layer documentation Improvements or additions to documentation effort:small < 1 hour

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Feature]: skills and commands were merged together, plugin-dev should account for this

2 participants

@sjnims